moonlitpath

Posted on Mar 27

Device Tree Bindings — What They Are and Why They Matter

#linux #kernel

written: 15th March, 2026

Motivation:

I was applying for GSoC 2026 - DT Bindings Project. In order to understand this project more, I decided to start off my learning about them first. I had also learnt about ACPI tables in this post while investigating my laptop's low power bug, and had encountered device trees. This made me curious about the GSoC project and so, I decided to learn about Device trees.

Along the way, I started finding them really interesting and worked on a patch to convert a DT binding to a DT Schema too! (i will talk about that in the next post)

What is a device tree?

A device tree is a data structure that describes hardware.

Hardware can be discoverable or non discoverable.

Discoverable -- some buses like PCI(e) and USB are discoverable -- can enumerate and identify connected devices at runtime
Non discoverable -- Buses like I2C, SPI, 1-Wire arent -- system must know how the devices are configured and what devices are connected --> this is where device trees are useful

Non discoverable devices hardware descriptions needed:-

CPU Cores
device specific details -- like memory addresses and interrupt requests.
board level componets like clock sources, reset signals etc These details OS/bootloader cannot guess

How to discover non discoverable components:

1) Modify OS/Bootloader directly to include the required information to discover devices--- but after ARM32 architecture -- too tedious to do..
2) ACPI tables -- mainly used on x86 architectures (pc, laptop), and some ARM64 platforms
3) Device trees -- used for embedded CPU arch, like ARM, RISC-V, MIPS, etc

Device Tree

it's a tree data structure that descibes hardware
described in --> Device Tree Source (.dts) files
compiled to --> Device Tree Blob (.dtb) format
by --> Device tree Compiler (dtc)

DTB can be directly linked to the bootloader, or passed to the OS by the bootloader

Device Tree Bindings

These are the sets of rules that check if the devicetree provided by the hardware are valid or not?
Eg. Arduino has temperature sensor. Temp sensors has hardware descriptions and device tree. these are validated against device tree bindings, and then identified.

Device Trees bindings are written in YAML format. These are machine readable,

The patch I will analyze is written by Krzysztof Kozlowski. It was provided as a reference in the GSoC Device Tree Bindings Project

Patch Link GSoC Project Details Link

YAML

Extra stuff added later:
This device is supported by only I2C bus. (it's explained in the next image)
But, some devices are supported by SPI protocol only. SPI protocol has 4 wires. There is no addressing system, and each chip gets a dedicated chip wire.

reg helps answer the question how a CPU identifies and reaches this specific chip of the bus

reg on I2C is the slave address.
Each chip has a dedicated slave address hardwired into it by the manufacturer.
Eg. here, reg=<0x11>

reg on spi identity of chip is the chip select line number. CPU has physical wires, there is no addressing, and reg is the number of wires connected.
Eg. here, reg=<0> --> connected to chip select line 0

maxItems can be > 1 in case of memory mapped peripherals -- that live directly inside the CPU's memory address space, and occupy separate regions of memory.
Eg. A display controller that has config registers at address1
and framebuffer memory at address2

TXT file -- old

Traditionally, they used to be written in txt format. These were just documentations written by the developer. These aren't machine readable, can't be verified quickly, and the documentation can be incomplete

Things I figured out along the way

DTS (device tree sources) -- describes the hardware
DT bindings -- how DTS should be constructed

Previously -- DT bindings were written in text in past
DT schema -- new format -- yaml
--new format which follows validation of bindings itself against meta schema
--validation of DTS against bindings

rules for writing bindings -- all new bindings must come in DT Schema

rules ->

adding new properties to DT bindings is not acceptable.
no adding linux specific subsystem names
don't describe software policies -- what OS should do
no need for properties for discoverable hardware
dual licence should be mentioned at start (GPL-2.0-only OR BSD-2-Clause)
bindings file name should be like -> vendor,device.yaml or vendor,soc-ip.yaml
binding patches and driver patches should be different
compatible --> should be specific -- no bus suffixes (if bus is there)
simple-mfd
---> simple multi functional device -- children does not depend on any features of parent
no reset lines -- no clocks -
for very simple devices
syscon - simple -- generic register range -- many pieces -- no 1 specific device
aka system controller -- has different bits for different pieces
dont use it to replace imp drivers
properties represent hardware characteristics

Resources:

DEV Community