Devicetree
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.
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 compatible 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 Documentation/devicetree/bindings; there is also a core DT schema defining the most basic components and syntax.
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 devicetree.org; they maintain the latest version of the Devicetree Specification, and maintain the related set of core DT schema.
Before the introduction of devicetrees, ARM kernels used board files. These were C files stored in arch/arm/mach-* 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)
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 dtc tool handles compiling DTS files into DTBs, as well as decompiling DTBs back into DTS.
Verifying device tree bindings and device tree sources
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.
Verifying DT bindings
To verify all DT bindings, run:
$ make dt_binding_check
You can also verify only a specific binding by providing its filename in the DT_SCHEMA_FILES option. This option takes either a filename or a directory name:
$ 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
Verifying DTS files
To verify all DTS files built with the selected defconfig options, run:
$ make dtbs_check
To verify a specific DTS, build the DTB target directly and provide the CHECK_DTBS=y option:
$ make CHECK_DTBS=y qcom/sm8450-hdk.dtb
You can also test a DTS against a specific subset of bindings by providing the DT_SCHEMA_FILES variable as mentioned in the previous section:
$ make CHECK_DTBS=y DT_SCHEMA_FILES=trivial-devices.yaml qcom/sm8450-hdk.dtb
See also
- From Linux kernel documentation:
References
todo enable refs extension
[1] https://www.mail-archive.com/[email protected]/msg01721.html [2] https://github.com/torvalds/linux/commit/b85a3ef4ac65169b65fd2fe9bec7912bbf475ba4