Devicetree - Revision history

Knuxify: /* Introduction */

2025-02-20T18:10:40Z

Introduction

← Older revision		Revision as of 18:10, 20 February 2025
Line 17:		Line 17:

	The following is a very simple example DTS (device tree source):		The following is a very simple example DTS (device tree source):

	~~{{note\|For a full guide to DTS syntax, see [[/DTS syntax]].}}~~

	<syntaxhighlight lang="dts" line>		<syntaxhighlight lang="dts" line>
Line 47:		Line 45:
	};		};
	</syntaxhighlight>		</syntaxhighlight>

			{{note\|For a full guide to DTS syntax, see [[/DTS syntax]].}}

	The devicetree acts like a map of the hardware; it describes where each component is in register space, and stores configuration values for them. It also describes components located on buses like I2C and SPI, and can carry some metadata about the board/device (like the RAM size/base address, model code or chassis type).		The devicetree acts like a map of the hardware; it describes where each component is in register space, and stores configuration values for them. It also describes components located on buses like I2C and SPI, and can carry some metadata about the board/device (like the RAM size/base address, model code or chassis type).

Knuxify: /* Introduction */

2025-02-20T18:10:14Z

Introduction

← Older revision		Revision as of 18:10, 20 February 2025
Line 18:		Line 18:
	The following is a very simple example DTS (device tree source):		The following is a very simple example DTS (device tree source):

	{{note\|For a full guide to DTS syntax, see [[/DTS syntax ~~guide~~]].}}		{{note\|For a full guide to DTS syntax, see [[/DTS syntax]].}}

	<syntaxhighlight lang="dts" line>		<syntaxhighlight lang="dts" line>

Knuxify at 18:07, 20 February 2025

2025-02-20T18:07:10Z

← Older revision		Revision as of 18:07, 20 February 2025
Line 1:		Line 1:
	{{Navbox devicetree}}		{{Navbox devicetree}}
	The '''devicetree''' (device tree, DT) is a ~~data~~ structure ~~which holds information about all components present on~~ a device. ~~This data~~ is ~~structured in nested nodes with key/value property pairs for configuration~~.		The '''devicetree''' (device tree, DT) is a tree structure that describes the hardware register layout and configuration of a device. In the Linux kernel, as well as in other DT-using projects like U-Boot, it is the primary method of discovering peripherals on embedded platforms such as ARM.

	~~In simpler terms -~~ a ~~devicetree tells~~ the ~~kernel~~ (~~or another DT-compatible piece of software/firmware like~~ a ~~bootloader~~) ~~where each component is~~ in ~~register space/on an I2C or similar bus~~, ~~and what settings to use to set~~ it ~~up. It is the basic mechanism for discovering components on embedded platforms, including ARM~~.		Devicetrees are written in a plaintext format known as the '''Device Tree Source (DTS)''' format. The DTS is later compiled into a '''Device Tree Blob (DTB)'''; in this form, it can be loaded by software/firmware.

	Devicetrees are ~~written in a plaintext format known as the~~ '''~~Device Tree Source (DTS)~~''' ~~format. The DTS~~ is ~~later compiled into a~~ '''~~Device Tree Blob (DTB)~~'''; ~~in this form, it can be loaded by software~~/~~firmware~~.		Devicetrees are validated using '''devicetree schema''', which is described in '''DT bindings'''; see [[/Bindings]] for more information.

	~~Devicetrees are validated using '''devicetree schema''', which is described by bindings; see [[/Bindings]] for more information.~~		== Introduction ==

	~~== History ==~~		An SoC (System-on-Chip) comprises of many subcomponents: timer, clock controller, I2C/SPI controller, GPIO, interrupt controller, SDHCI storage, USB, and so on. Each needs its own driver, and for most parts the exact implementation differs between chip manufacturers. Most of them expose a static range of addresses in MMIO (memory-mapped IO) space that the system can use to communicate with them.

	~~The initial version of the devicetree standard was developed as part of the OpenFirmware initiative; from this standard~~, the ~~Flattened Device Tree (FDT) emerged and was adopted by the Linux kernel for PowerPC platforms. Around 2009~~, ~~discussions began to include FDT support for ARM[1]. It was eventually added and first~~ device ~~trees began to appear in 2011[2], although the format didn't see wider usage (especially in vendor kernels) until around 2013/2014~~.		Additionally, there may be other peripherals connected to the system - often through a bus like I2C or SPI, or as a simple device controlled by a GPIO.

	~~Nowadays~~, ~~the devicetree standard is managed~~ by ~~[https://www~~.~~devicetree.org/ devicetree.org]; they maintain the latest version of the [https://www.devicetree.org/specifications Devicetree Specification]~~ and the ~~related set of [https://github.com/devicetree-org/dt-schema core DT schema]~~.		On a standard x86 system, peripherals are usually autodetected, either through ACPI, or by being on a bus like PCI or USB. On most embedded platforms like ARM, however, there is no such autodetection method, and the hardware needs to be described manually.

	~~Before~~ the ~~introduction~~ of ~~devicetrees~~, ~~ARM kernels used~~ '''~~board files~~'''. These were C files stored in <code>arch/arm/mach-*</code> which served a similar purpose to devicetrees - they contained structures for defining component configuration ("platform data"). Unlike device trees however, they could also define C functions, since they were regular C sources compiled into the kernel. Board files technically still exist (citation needed?), but are no longer in wide use.		The solution for this, used by both the Linux kernel, as well as a variety of other projects like U-Boot, is the '''devicetree'''.

	~~== Device Tree Source~~ (~~DTS~~) ~~basics ==~~		The following is a very simple example DTS (device tree source):

	~~The following is~~ a ~~simple DTS file~~ to ~~demonstrate the~~ DTS syntax~~. For a more in-depth syntax guide~~, see [[~~Devicetree~~/DTS syntax]].		{{note\|For a full guide to DTS syntax, see [[/DTS syntax guide]].}}

	~~{{SyntaxHighlight header\|foo.dts}}~~
	<syntaxhighlight lang="dts" line>		<syntaxhighlight lang="dts" line>
	/dts-v1/;		/dts-v1/;
Line 27:		Line 26:
	#address-cells = <1>;		#address-cells = <1>;
	#size-cells = <1>;		#size-cells = <1>;

	my_node: node1@1000 {		my_node: node1@1000 {
	compatible = "vendor,foo";		compatible = "vendor,foo";
	reg = <0x1000 0x54>;		reg = <0x1000 0x54>;
	vendor,bar-factor = <0x2a>;		vendor,bar-factor = <0x2a>;
	};

	~~node2@2000 {~~
	~~compatible = "vendor,bar";~~
	~~reg = <0x2000 0xa4>;~~
	~~vendor,baz-companion = <&my_node>;~~
	};		};

Line 54:		Line 47:
	};		};
	</syntaxhighlight>		</syntaxhighlight>

			The devicetree acts like a map of the hardware; it describes where each component is in register space, and stores configuration values for them. It also describes components located on buses like I2C and SPI, and can carry some metadata about the board/device (like the RAM size/base address, model code or chassis type).

			Devicetrees are written in the '''DTS''' (Device Tree Source) format; the source file can then be compiled into a '''DTB''' (Device Tree Blob), which software can parse to get all the necessary information about a given platform.

			On modern systems, the bootloader loads the DTB into a set place in memory; the Linux kernel then decodes the information from the DTB and initializes all the components based on it. (On 32-bit ARM, which predates widespread adoption of DTBs and DTB-capable bootloaders, an alternative mechanism exists in Linux to load a DTB appended to the kernel image).

			== History ==

			The initial version of the devicetree standard was developed as part of the OpenFirmware initiative; from this standard, the Flattened Device Tree (FDT) emerged and was adopted by the Linux kernel for PowerPC platforms. Around 2009, discussions began to include FDT support for ARM[1]. It was eventually added and first device trees began to appear in 2011[2], although the format didn't see wider usage (especially in vendor kernels) until around 2013/2014.

			Nowadays, the devicetree standard is managed by [https://www.devicetree.org/ devicetree.org]; they maintain the latest version of the [https://www.devicetree.org/specifications Devicetree Specification] and the related set of [https://github.com/devicetree-org/dt-schema core DT schema].

			Before the introduction of devicetrees, ARM kernels used '''board files'''. These were C files stored in <code>arch/arm/mach-*</code> which served a similar purpose to devicetrees - they contained structures for defining component configuration ("platform data"). Unlike device trees however, they could also define C functions, since they were regular C sources compiled into the kernel. Board files technically still exist (citation needed?), but are no longer in wide use.

			== Devicetree sources in the Linux kernel ==

			TODO

	== Verifying DTS files ==		== Verifying DTS files ==

Knuxify at 19:46, 19 February 2025

2025-02-19T19:46:27Z

Show changes

Knuxify: add devicetree navbox

2025-02-19T19:15:11Z

add devicetree navbox

← Older revision		Revision as of 19:15, 19 February 2025
Line 1:		Line 1:
			{{Navbox devicetree}}
	The '''devicetree''' (device tree, DT) is a data structure which holds information about all components present on a device. This data is structured in nested nodes with key/value property pairs for configuration.		The '''devicetree''' (device tree, DT) is a data structure which holds information about all components present on a device. This data is structured in nested nodes with key/value property pairs for configuration.

Knuxify: Knuxify moved page User:Knuxify/Draft:Devicetree to Devicetree: move to main namespace

2025-02-19T18:06:05Z

Knuxify moved page User:Knuxify/Draft:Devicetree to Devicetree: move to main namespace

← Older revision		Revision as of 18:06, 19 February 2025
(No difference)

Knuxify: /* Device Tree Source (DTS) basics */

2025-02-19T17:58:46Z

Device Tree Source (DTS) basics

Show changes

Knuxify at 16:41, 19 February 2025

2025-02-19T16:41:48Z

← Older revision		Revision as of 16:41, 19 February 2025
Line 1:		Line 1:
	The '''devicetree''' (device tree, DT ~~(DTS/DTB)~~) is a data structure which holds information about all components present on a device. This data is structured in nested nodes with key/value property pairs for configuration.		The '''devicetree''' (device tree, DT) is a data structure which holds information about all components present on a device. This data is structured in nested nodes with key/value property pairs for configuration.

	In simpler terms - a devicetree tells the kernel (or another DT-compatible piece of software/firmware like a bootloader) where each component is in register space/on an I2C or similar bus, and what settings to use to set it up. It is the basic mechanism for discovering components on embedded platforms, including ARM.		In simpler terms - a devicetree tells the kernel (or another DT-compatible piece of software/firmware like a bootloader) where each component is in register space/on an I2C or similar bus, and what settings to use to set it up. It is the basic mechanism for discovering components on embedded platforms, including ARM.

			Devicetrees are written in a plaintext format known as the '''Device Tree Source (DTS)''' format. The DTS is later compiled into a '''Device Tree Blob (DTB)'''; in this form, it can be loaded by software/firmware.

	Devicetrees are validated using '''devicetree schema''', which is described by bindings; see [[/Bindings]] for more information.		Devicetrees are validated using '''devicetree schema''', which is described by bindings; see [[/Bindings]] for more information.
Line 13:		Line 15:
	Before the introduction of devicetrees, ARM kernels used '''board files'''. These were C files stored in <code>arch/arm/mach-*</code> which served a similar purpose to devicetrees - they contained structures for defining component configuration ("platform data"). Unlike device trees however, they could also define C functions, since they were regular C sources compiled into the kernel. Board files technically still exist (citation needed?), but are no longer in wide use.		Before the introduction of devicetrees, ARM kernels used '''board files'''. These were C files stored in <code>arch/arm/mach-*</code> which served a similar purpose to devicetrees - they contained structures for defining component configuration ("platform data"). Unlike device trees however, they could also define C functions, since they were regular C sources compiled into the kernel. Board files technically still exist (citation needed?), but are no longer in wide use.

	== Device Tree Source (DTS) ~~and Device Tree Blob (DTB) ==~~		== Device Tree Source (DTS) basics ==

	Devicetrees are written in a plaintext format known as the '''Device Tree Source (DTS)''' format. The DTS is later compiled into a '''Device Tree Blob (DTB)'''; in this form, it can be loaded by software/firmware.

	~~The <code>dtc</code> tool handles compiling DTS files into DTBs, as well as decompiling DTBs back into DTS.~~

	~~=== Device Tree Source~~ basics ===

	Here is a very simple DTS file to explain the basics of what you might see in a device tree source file:		Here is a very simple DTS file to explain the basics of what you might see in a device tree source file:
Line 89:		Line 85:
	$ make CHECK_DTBS=y DT_SCHEMA_FILES=trivial-devices.yaml qcom/sm8450-hdk.dtb		$ make CHECK_DTBS=y DT_SCHEMA_FILES=trivial-devices.yaml qcom/sm8450-hdk.dtb
	</syntaxhighlight>		</syntaxhighlight>

			== Working with DTC ==

			The <code>dtc</code> tool handles compiling DTS files into DTBs, as well as decompiling DTBs back into DTS. (TODO: add instructions)

	== See also ==		== See also ==

Knuxify at 12:22, 17 February 2025

2025-02-17T12:22:59Z

← Older revision		Revision as of 12:22, 17 February 2025
Line 94:		Line 94:
	* From Linux kernel documentation:		* From Linux kernel documentation:
	** [https://docs.kernel.org/devicetree/bindings/dts-coding-style.html Devicetree Sources (DTS) Coding Style]		** [https://docs.kernel.org/devicetree/bindings/dts-coding-style.html Devicetree Sources (DTS) Coding Style]
	** [https://docs.kernel.org/devicetree/bindings/writing-schema.html Writing Devicetree Bindings in json-schema]
	** [https://docs.kernel.org/devicetree/bindings/writing-bindings.html DOs and DON’Ts for designing and writing Devicetree bindings]
	** [https://docs.kernel.org/devicetree/bindings/submitting-patches.html Submitting Devicetree (DT) binding patches]
	* On elinux.org:		* On elinux.org:
	** [https://elinux.org/Device_Tree_Reference Device Tree Reference]		** [https://elinux.org/Device_Tree_Reference Device Tree Reference]

Knuxify at 12:22, 17 February 2025

2025-02-17T12:22:20Z

← Older revision		Revision as of 12:22, 17 February 2025
Line 3:		Line 3:
	In simpler terms - a devicetree tells the kernel (or another DT-compatible piece of software/firmware like a bootloader) where each component is in register space/on an I2C or similar bus, and what settings to use to set it up. It is the basic mechanism for discovering components on embedded platforms, including ARM.		In simpler terms - a devicetree tells the kernel (or another DT-compatible piece of software/firmware like a bootloader) where each component is in register space/on an I2C or similar bus, and what settings to use to set it up. It is the basic mechanism for discovering components on embedded platforms, including ARM.

	Devicetrees are validated using '''devicetree schema~~'''; this schema specifies allowed properties for nodes based on their <code>compatible</code> string. Devicetree schema is defined through '''bindings~~''', ~~YAML files containing schema information (older bindings use TXT format, but this~~ is ~~deprecated). Bindings for most Linux components can be found in <code>Documentation/devicetree/~~bindings~~</code>~~; ~~there is also a~~ [~~https:~~/~~/github.com/devicetree-org/dt-schema core DT schema~~] ~~defining the most basic components and syntax~~.		Devicetrees are validated using '''devicetree schema''', which is described by bindings; see [[/Bindings]] for more information.

	== History ==		== History ==
Line 67:		Line 67:
	On node 2 there is also a property, <code>vendor,baz-companion</code>, which takes a pointer to another node - here the one we labeled "my_node".		On node 2 there is also a property, <code>vendor,baz-companion</code>, which takes a pointer to another node - here the one we labeled "my_node".

	== Verifying ~~device tree bindings and device tree sources~~ ==		== Verifying DTS files ==

	The Linux kernel has tools for ~~verifying the correctness of device tree schema bindings, as well as~~ making sure that device tree sources (DTS) use the bindings correctly. These are useful when writing device sources; getting ~~both of these~~ checks to pass is also mandatory for upstream inclusion of a ~~binding/~~DTS.		The Linux kernel has tools for making sure that device tree sources (DTS) use the bindings correctly. These are useful when writing device sources; getting
			the DT checks to pass is also mandatory for upstream inclusion of a DTS.
	~~=== Verifying DT bindings ===~~

	~~To verify all DT bindings, run:~~

	~~<syntaxhighlight lang="shell-session">~~
	~~$ make dt_binding_check~~
	~~</syntaxhighlight>~~

	~~You can also verify only a specific binding by providing its filename in the <code>DT_SCHEMA_FILES</code> option. This option takes either a filename or a directory name:~~

	~~<syntaxhighlight lang="shell-session">~~
	~~$ make dt_binding_check DT_SCHEMA_FILES=brcm,bcm590xx.yaml # Checks all bindings named brcm,bcm590xx.yaml~~
	~~$ make dt_binding_check DT_SCHEMA_FILES=qcom # Checks all bindings in any (sub)folder named "qcom"~~
	~~$ make dt_binding_check DT_SCHEMA_FILES=/gpio/ # Checks all bindings in /gpio folder~~
	~~</syntaxhighlight>~~

	~~=== Verifying DTS files ===~~

	To verify all DTS files built with the selected defconfig options, run:		To verify all DTS files built with the selected defconfig options, run: